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Manual upgrades/downgrades 


This is for if you: 


can't upgrade/downgrade from stable to beta or vice versa using MAIN MENU > UPDATES & 
DOWNLOADS > UPDATE TYPE > “Stable” or “Beta” and updating or using SSH for the same 
thing, 

want to downgrade to an older revision, or 

want to install a custom version of Batocera. 


The Batocera drive layout 


First a little explanation of how Batocera is laid out on your drive, as this will help in understanding 
exactly what files need to be placed where later on: 


The boot partition is what appears as the FAT32 partition when you plug the drive into another 
system. The boot partition contains the files required to boot, this is mounted in read-only mode 
to /boot/ during boot. The read-only batocera SquashFS file is also contained in the boot 
partition. On boot, this filesystem is mounted at / to run Batocera proper. You'll also find 
batocera-boot.conf here. In Batocera v31 and lower, the custom splash videos you have 
uploaded would be copied here too. This partition is assigned 6 GB of space (4 GB with older 
images of Batocera), with 2 GB used by Batocera. Files in only this partition are overwritten 
when updating Batocera; it's relatively simple to upgrade/downgrade Batocera versions 
because of this design. 

The userdata contains “the rest”, all the BIOS files, ROMs, save data, user configuration 
(including batocera. conf). This partition is not touched when upgrading/downgrading. This is 
designed to be portable between all versions of Batocera, even Batocera builds running on 
different platforms (granted, weaker platforms like SBCs won't magically gain the ability to play 
ROMs for emulators they don't have). 


Upgrading/downgrading Batocera 


In Batocera 5.23 and higher, it is advised to upgrade/downgrade using the batocera-upgrade 
command via SSH. Grab the URL of the version you want to upgrade/downgrade to and run 
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batocera-upgrade [URL]. For example, to upgrade to the latest stable for x86_64: 
batocera-upgrade https://batocera.org/upgrades/x86 64/stable/last 


Or to downgrade to a specific older version, like in the example below to downgrade to Batocera 36 
for PC x86_64. Don't copy that command on another architecture like a Raspberry Pi, you need to 
adapt the URL to it. 


batocera-upgrade 
https://mirrors.o2switch.fr/batocera/x86 64/stable/last/archives/36/ 


used to display the arch that should be used. For example, 


i, The command cat /boot/boot/batocera.board can be 
on a PC this will display x86_64. 


You should then see output similar to this: 


Starting the upgrade... 

url: https://updates.batocera.org/x86 64/stable/last/boot.tar.xz 

need to download 1876mb 

/userdata/system/upgrade/boot.tar.xz 0% [ ] 
9.55M 1.82MB/s eta 19m 42s 


For very old versions, from Batocera 5.7 to 5.22, the command (for PC x86_64, please adapt to the 
right architecture) would instead be: 


/recalbox/scripts/recalbox-upgrade.sh 
https://batocera.org/upgrades/x86 64/stable/last 


These commands download the compressed upgrade (or potentially downgrade) file and expand it to 
overwrite the Batocera system on the boot partition. Upgrading or downgrading like this doesn't 
remove any of your user data (ROMs, saves, metadata...). Like never, ever. 


On the next reboot of Batocera, it will instead use the upgraded version. If the automatic upgrade tool 
is not suitable for your purpose, then you can manually upgrade/downgrade as specified below 
instead. 


Upgrade from a local boot.tar.xz file 


To upgrade/downgrade manually from a downloaded boot. tar. xz file: 


1. Download the boot.tar. xz file of the version you want. The official ones are available at 
https://mirrors.o2switch.fr/batocera/ (for older versions, navigate to your architecture and go to 
/stable/last/archives/). Here's a list of architectures and links to their builds. 

2. Backup your boot configuration files (batocera-boot.conf and config. txt) from the 
Batocera machine (if you have edited them and require the edits to boot properly) to a safe 
location. 
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3. Unzip the boot.tar.xz file (it's just like a . zip, you can use 7-zip on Windows) to get the 
boot. tar file. 

4. Unzip the boot. tar file into the root of your Batocera drive's boot partition (this is the default 
partition you see when inserting the drive into Windows) and overwrite the existing files. You 
may have to assign a drive letter under Windows Disk Management to see it in the file explorer. 

5. Restore your boot configuration files if you wish to do so. 


What the batocera-upgrade command does 


Ordinarily, the built-in updating tool will do all of the following automatically: 


1. Download the boot image file to /userdata/system/upgrade/boot.tar.xz in the userdata 
partition 

2. Check the md5sum of the file to ensure that it was downloaded correctly (this may take a bit of 

time, depending on the speed of your drive) 

. After validation, remount the boot partition in rewritable mode 

4. Back up your boot config files: /boot/batocera-boot.conf to /boot/batocera- 
boot.conf.upgrade and /boot/config.txt to /boot/config.txt.upgrade 

5. Unzip the contents of /userdata/system/upgrade/boot.tar.xz to /boot/ 

6. Restore your boot config files: /boot/batocera-boot.conf.upgrade to /boot/batocera- 
boot.conf and /boot/config.txt.upgrade to /boot/config.txt 

7. Do a “final cleanup” 

8. Remove /userdata/system/upgrade/boot.tar.xz 


WwW 


Not enough space to update 


Userdata partition 


If you get an error message telling you that you don't have enough space on your userdata partition 
to download the file, there might be several reasons: 


e Your drive is less than 8 GB total. Batocera can run on these drives but you will be missing out 
on using the built-in updater. 

e Your userdata partition does not have at least 2 GB additional free space to download the 
boot.tar.xz file. 


To work around there not being enough free space in the userdata partition, you can do any of the 
following: 


e Temporarily remove some of your ROMs, BIOS, and other userdata to make enough free space 
to download the boot. tar. xz file. 

e Download the boot.tar.xz from the server for the intended Batocera version onto another 
computer, connect the Batocera drive to it, and extract the contents of boot. tar directly to 
the boot partition of Batocera. 
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Boot partition 


If you get an error message telling you that you don't have enough space on your Batocera boot 
partition while attempting to upgrade, there might be several reasons: 


e Your drive is less than 8 GB total. Batocera can run on these drives but you will be missing out 
on using the built-in updater. 

e On Batocera v31 and lower, the splash video file(s) (which are copied to the /boot partition) 
are/is taking up too much space. Remove then/it, reboot and try to upgrade again. 

e Your first installation was an older version of Batocera, where the /boot partition was initially 
assigned less space (compared to installations of newer Batocera versions). 

e Your installation is corrupted. 


To work around there not being enough free space in the boot partition, you can do any one of the 
following: 


Use another computer 


Use another computer to extract the update files onto the Batocera drive. Be aware that by doing this 
you would have to do this manual workaround every time you need to update. 


1. Insert your drive into another computer 

2. Back up the contents of the FAT32 boot partition of the Batocera drive (Windows should only be 
able to see this partition and nothing else by default) to another location 

3. Delete the /boot/batocera file from the Batocera drive (it is just called batocera without a 
file-extension and is about 2 GB large (smaller in older versions)) 

4. Extract the boot. tar file to the root of that partition 

5. Replug the Batocera back into your Batocera machine and boot Batocera. 


Q If Batocera fails to boot, you can restore the data you backed up in step 2. 


Remove the old version first 
Remove the old version of Batocera before overwriting it with the update. Be aware that by doing this 
you would have to do this manual workaround every time you need to update. 
1. Boot into Batocera, SSH into it or use the file manager's xterm and run the following: 
mount -o remount,rw /boot 


2. Backup your /boot/boot/batocera file to another device or the userdata partition if you 
have enough space there (cp /boot/boot/batocera /userdata/system/batocera- 
backup, or you can exit the xterm with [ALt]+[F4] and then use the file manager to copy the 
file to your /userdata/system/ folder) 

3. Run the following command to delete the batocera file and immediately upgrade: 
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rm -i /boot/boot/batocera && batocera-upgrade 


Confirm the file you want to delete. 


You should then get an output that looks like this: 
Starting the upgrade... 
t url: 
https://updates.batocera.org/x86 64/beta/last/boot.tar.xz 
need to download 1876mb 


m/upgrade/boot.tar.xz 0% [ ] 
9.55M 1.82MB/s eta 19m 42s 


4. Wait for the upgrade to completely finish, then reboot to apply the changes. 


cp /userdata/system/batocera-backup /boot/boot/batocera && rm 
/userdata/system/batocera-backup 


Flash a spare drive 


Flash a spare USB/portable hard-drive with a new copy of Batocera and boot into that, copy all your 
/userdata/ (everything in Share) from your old Batocera drive to your spare USB/portable hard- 
drive and then reflash the old Batocera drive with a new version of Batocera (or just continue to use 
your spare USB/portable hard-drive). 


Reflash the drive 


Backup your /userdata/ to another device (you may lose file attributes by doing this, causing 
problems with WINE/Cemu) and reflash Batocera. 


Manually extend the boot partition 


Extend the boot partition of your drive using an advanced tool like gparted or ® GNOME Disks (a.k.a. 
gnome-disk-utility). This will likely destroy your userdata partition, so back up all your ROMs, 
saves, configs, etc. first. This is not the recommended method, as it may cause irreversible damage to 
your drive and it may damage the MBR/GPT table, causing the drive to become unbootable. Consider 
the other options first or just staying on your current version of Batocera. Batocera v30 requires at 
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least 6 GB total assigned to the boot partition and 2 GB free space in the userdata partition to be able 
to use the built-in updater. 
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